IMoniker - Item Moniker Implementation
Item monikers
are used to identify objects within containers, such as a portion of a
document, an embedded object within a compound document, or a range of cells
within a spreadsheet. Item monikers are often used in combination with file monikers;
a file moniker is used to identify the container while an item moniker is used
to identify the item within the container.
An item
moniker contains a text string; this string is used by the container object to
distinguish the contained item from the others. The container object must
implement the IOleItemContainer interface; this interface enables the
item moniker code to acquire a pointer to an object, given only the string that
identifies the object.
When to Use
If you re a
moniker client (that is, you re using a moniker to get an interface pointer to
an object), you typically don t need to know the class of the moniker you re
using; you simply call methods using an IMoniker interface pointer.
If you re a
moniker provider (that is, you re handing out monikers that identify your
objects to make them accessible to moniker clients), you must use item monikers
if the objects you re identifying are contained within another object and can
be individually identified using a string. You ll also need to use another type
of moniker (for example, file monikers) in order to identify the container
object.
To use item
monikers, you must use the CreateItemMonikerLHMVWY function to create the monikers. In order
to allow your objects to be loaded when an item moniker is bound, the container
of your objects must implement the IOleItemContainer interface.
The most
common example of moniker providers are OLE applications that support linking.
If your OLE application supports linking to objects smaller than a file-based
document, you need to use item monikers. For a server application that allows
linking to a selection within a document, you use the item monikers to identify
those objects. For a container application that allows linking to embedded
objects, you use the item monikers to identify the embedded objects.
Remarks
IMoniker::BindToObject
If pmkToLeft
is NULL, this method returns E_INVALIDARG. Otherwise, the method calls IMoniker::BindToObject on the pmkToLeft
parameter, requesting an IOleItemContainer interface pointer. The method
then calls IOleItemContainer::GetObject, passing the string contained
within the moniker, and returns the requested interface pointer.
IMoniker::BindToStorage
If pmkToLeft
is NULL, this method returns E_INVALIDARG. Otherwise, the method calls IMoniker::BindToObject
on the pmkToLeft parameter, requesting an IOleItemContainer
interface pointer. The method then calls IOleItemContainer::GetObjectStorage
for the requested interface.
IMoniker::Reduce
This method
returns MK_S_REDUCED_TO_SELF and passes back the same moniker.
IMoniker::ComposeWith
If pmkRight
is an anti-moniker, the returned moniker is NULL; if pmkRight is a
composite whose leftmost component is an anti-moniker, the returned moniker is
the composite after the leftmost anti-moniker is removed. If pmkRight is
not an anti-moniker, the method combines the two monikers into a generic
composite if fOnlyIfNotGeneric is FALSE; if fOnlyIfNotGeneric is
TRUE, the method returns a NULL moniker and a return value of MK_E_NEEDGENERIC.
IMoniker::Enum
This method
returns S_OK and sets *ppenumMoniker to NULL.
IMoniker::IsEqual
This method
returns S_OK if both monikers are item monikers and their display names are
identical (using a case-insensitive comparison); otherwise, the method returns
S_FALSE.
IMoniker::Hash
This method
calculates a hash value for the moniker.
IMoniker::IsRunning
If pmkToLeft
is NULL, this method returns TRUE if pmkNewlyRunning is non-NULL and is
equal to this moniker. Otherwise, the method checks the ROT to see whether this
moniker is running.
If pmkToLeft
is non-NULL, the method calls IMoniker::BindToObject on the pmkToLeft
parameter, requesting an IOleItemContainer interface pointer. The method
then calls IOleItemContainer::IsRunning, passing the string contained
within this moniker.
IMoniker::GetTimeOfLastChange
If pmkToLeft
is NULL, this method returns MK_E_NOTBINDABLE. Otherwise, the method creates a
composite of pmkToLeft and this moniker and uses the ROT to access the
time of last change. If the object is not in the ROT, the method calls IMoniker::GetTimeOfLastChange
on the pmkToLeft parameter.
IMoniker::Inverse
This method
returns an anti-moniker (i.e., the results of calling CreateAntiMoniker).
IMoniker::CommonPrefixWith
If the other
moniker is an item moniker that is equal to this moniker, this method sets *ppmkPrefix
to this moniker and returns MK_S_US; otherwise, the method calls the MonikerCommonPrefixWith function. This function
correctly handles the case where the other moniker is a generic composite.
IMoniker::RelativePathTo
This method
returns MK_E_NOTBINDABLE and sets *ppmkRelPath to NULL.
IMoniker::GetDisplayName
This method
returns the concatenation of the delimiter and the item name that were
specified when the item moniker was created.
IMoniker::ParseDisplayName
If pmkToLeft
is NULL, this method returns MK_E_SYNTAX. Otherwise, the method calls IMoniker::BindToObject on the pmkToLeft parameter,
requesting an IOleItemContainer interface pointer. The method then calls
IOleItemContainer::GetObject, requesting an IParseDisplayName interface pointer to the
object identified by the moniker, and passes the display name to IParseDisplayName::ParseDisplayName.
IMoniker::IsSystemMoniker
This method
returns S_OK and indicates MKSYS_ITEMMONIKER.
See Also